<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Control flow
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot005.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot003.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc10">2.3</A>&nbsp;&nbsp;Control flow</H2><UL>
<LI><A HREF="embroot006.html#toc6">Control flow and search</A>
<LI><A HREF="embroot006.html#toc7">Asynchronous events</A>
<LI><A HREF="embroot006.html#toc8">The yield-resume model</A>
<LI><A HREF="embroot006.html#toc9">Summary of EC_resume() arguments</A>
</UL>


ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and a C or C++ main program are like threads running in a
single process. Each maintains its state and methods for exchanging
<A NAME="@default11"></A>
<A NAME="@default12"></A>
data and yielding control to the other thread.<BR>
<BR>
The main method of sending data from C++ to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is by posting
<A NAME="@default13"></A>
goals for it to solve. All posted goals are solved in conjunction
with each other, and with any previously posted goals that have
succeeded.<BR>
<BR>
Data is passed back by binding logical variables within the goals.
<A NAME="@default14"></A><BR>
<BR>
<A NAME="@default15"></A>
Control is explicit in C++. After posting some goals, the C++ program
calls the <CODE>EC_resume()</CODE> function and these goals are all
solved. A return code says whether they were successfully solved
or whether a failure occurred.<BR>
<BR>
In ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> control is normally implicit. Control returns to C++ when all
goals have been solved.
<PRE CLASS="verbatim">
    #include        "eclipseclass.h"

    main()
    {
        ec_init();

        /* writeln("hello world"), */
        post_goal(term(EC_functor("writeln",1),"hello world"));
        EC_resume();
        ec_cleanup(0);
    }
</PRE>The above is an example program that posts a goal and executes it.<BR>
<BR>
<A NAME="toc6"></A>
<H3 CLASS="subsection"><A NAME="htoc11">2.3.1</A>&nbsp;&nbsp;Control flow and search</H3>
Using this model of communication it is possible to construct programs where
execution of C++ code and search within the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> are interleaved.<BR>
<BR>
<A NAME="@default16"></A>
<A NAME="@default17"></A>
<A NAME="@default18"></A>
If you post a number of goals (of which some are non-deterministic) and
resume the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> execution and the goals succeed, then control returns
to the C++ level. By posting a goal that fails, the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> execution
will fail back into the previous set of goals and these will succeed with
a different solution. 
<PRE CLASS="verbatim">
    #include        "eclipseclass.h"

    main()
    {
        ec_init();
        EC_ref Pred;

        post_goal(term(EC_functor("current_built_in",1),Pred));
        while (EC_succeed == EC_resume())
        {
            post_goal(term(EC_functor("writeln",1),Pred));
            post_goal(EC_atom("fail"));
        }
        ec_cleanup(0);
    }
</PRE>The above example prints all the built ins available in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.
When <CODE>EC_resume()</CODE> returns <CODE>EC_succeed</CODE> there is a solution
to a set of posted goals, and we print out the value of <CODE>Pred</CODE>.
otherwise <CODE>EC_resume()</CODE> returns <CODE>EC_fail</CODE> to indicate
that no more solutions to any set of posted goals is available.<BR>
<BR>
<A NAME="@default19"></A>
It is possible also to cut such search. So for example one could modify
the example above to only print the 10th answer. Initially one simply
fails, but at the tenth solution one cuts further choices. Then
one prints the value of 'Pred'.
<PRE CLASS="verbatim">
    #include        "eclipseclass.h"

    main()
    {
        ec_init();
        EC_ref Pred,Choice;
        int i = 0;

        post_goal(term(EC_functor("current_built_in",1),Pred));
        while (EC_succeed == EC_resume(Choice))
        {
            if (i++ == 10)
            {
                Choice.cut_to();
                break;
            }
            post_goal(term(EC_atom("fail")));
        }
        post_goal(term(EC_functor("writeln",1),Pred));
        EC_resume():
        ec_cleanup(0);
    }
</PRE>
<A NAME="@default20"></A>
When <CODE>EC_resume()</CODE> is called with an <CODE>EC_ref</CODE> argument, this
is for data returned by the <CODE>EC_resume()</CODE> If the return code is
<CODE>EC_succeed</CODE> The <CODE>EC_ref</CODE> is set to a choicepoint identifier
which can be used for cutting further choices at that point.<BR>
<BR>
<A NAME="toc7"></A>
<H3 CLASS="subsection"><A NAME="htoc12">2.3.2</A>&nbsp;&nbsp;Asynchronous events</H3>
<A NAME="@default21"></A>
<A NAME="@default22"></A>
The posting of goals and building of any ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms in general
cannot be done asynchronously to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> execution. It has to
be done after the <CODE>EC_resume()</CODE> function has returned.<BR>
<BR>
<A NAME="@default23"></A>
Sometimes it may be necessary to signal some asynchronous event to
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, for example to implement a time-out. To do this one
posts a named event to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. At the next synchronous point
within the eclipse execution, the handler for that event is
invoked.
<PRE CLASS="verbatim">
    /* C++ code, possibly within a signal handler */
    post_event(EC_atom("timeout"));

    /* ECLiPSe code */
    handle_timeout(timeout) :-
        &lt;appropriate action&gt;

    :- set_event_handler(timeout, handle_timeout/1).
</PRE>
<A NAME="toc8"></A>
<H3 CLASS="subsection"><A NAME="htoc13">2.3.3</A>&nbsp;&nbsp;The yield-resume model</H3>
<A NAME="@default24"></A>
<A NAME="@default25"></A>
<A NAME="@default26"></A>
Although implicitly yielding control when a set of goals succeeds
or fails is often enough, it is possible to explicitly yield
control to the C++ level. This is done with the
<A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default27"></A>
predicate. This yields control to the calling C++ program.
The arguments are used for passing data to C++ and from C++.<BR>
<BR>
When <A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default28"></A> is called within ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> code, the <CODE>EC_resume()</CODE>
function returns the value <CODE>EC_yield</CODE> so one can recognise this case.
The data passed out via the first argument of <A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default29"></A>
can be accessed from C++ via the <CODE>EC_ref</CODE> argument to <CODE>EC_resume()</CODE>.
The data received in the second argument of <A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default30"></A> is either
the list of posted goals, or an <CODE>EC_word</CODE> passed as an input
argument to <CODE>EC_resume()</CODE>.
<PRE CLASS="verbatim">
    yield(out(1,2),InData),
</PRE>
In this example the compound term <CODE>out(1,2)</CODE> is passed to C++.
If we had previously called:
<PRE CLASS="verbatim">
    EC_ref FromEclipse;
    result = EC_resume(FromEclipse);
</PRE>then <CODE>result</CODE> would be <CODE>EC_yield</CODE> and <CODE>FromEclipse</CODE> would
refer to <CODE>out(1,2)</CODE>. If then we resumed execution with:
<PRE CLASS="verbatim">
    result = EC_resume(EC_atom("ok"),FromEclipse);
</PRE>then the variable <CODE>InData</CODE> on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side
would be set to the atom 'ok'.<BR>
<BR>
<A NAME="toc9"></A>
<H3 CLASS="subsection"><A NAME="htoc14">2.3.4</A>&nbsp;&nbsp;Summary of EC_resume() arguments</H3>
<A NAME="@default31"></A>
<CODE>EC_resume()</CODE> can be called with two optional arguments. An
input argument that is an <CODE>EC_word</CODE> and an output that is an
<CODE>EC_ref</CODE>.<BR>
<BR>
If the input argument is omitted, input is taken as the list of posted
goals. Otherwise the input to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is exactly that argument.<BR>
<BR>
If the output argument is present, its content depends on the value
returned by <CODE>EC_resume()</CODE>. If it returns <CODE>EC_succeed</CODE> it is
<A NAME="@default32"></A>
the choicepoint identifier. If it returns <CODE>EC_yield</CODE> It is the
first argument to the <A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default33"></A> goal. If it returns <CODE>EC_fail</CODE>
it is not modified.
<HR>
<A HREF="embroot005.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot003.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
</BODY>
</HTML>
